<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->

<B><A HREF="WRITE.html">WRITE(2)</A></B>		  FreeBSD System Calls Manual		      <B><A HREF="WRITE.html">WRITE(2)</A></B>


</PRE>
<H2>NAME</H2><PRE>
     <B>write</B>, <B>writev</B>, <B>pwrite</B> - write output


</PRE>
<H2>SYNOPSIS</H2><PRE>
     <B>#include</B> <B>&lt;sys/types.h&gt;</B>
     <B>#include</B> <B>&lt;sys/uio.h&gt;</B>
     <B>#include</B> <B>&lt;unistd.h&gt;</B>

     <I>ssize</I><B>_</B><I>t</I>
     <B>write</B>(<I>int</I> <I>d</I>, <I>const</I> <I>void</I> <I>*buf</I>, <I>size</I><B>_</B><I>t</I> <I>nbytes</I>)

     <I>ssize</I><B>_</B><I>t</I>
     <B>writev</B>(<I>int</I> <I>d</I>, <I>const</I> <I>struct</I> <I>iovec</I> <I>*iov</I>, <I>int</I> <I>iovcnt</I>)

     <I>ssize</I><B>_</B><I>t</I>
     <B>pwrite</B>(<I>int</I> <I>d</I>, <I>const</I> <I>void</I> <I>*buf</I>, <I>size</I><B>_</B><I>t</I> <I>nbytes</I>, <I>off</I><B>_</B><I>t</I> <I>offset</I>)


</PRE>
<H2>DESCRIPTION</H2><PRE>
     <B>Write</B>() attempts to write <I>nbytes</I> of data to the object referenced by the
     descriptor <I>d</I> from the buffer pointed to by <I>buf</I>. <B>Writev</B>() performs the
     same action, but gathers the output data from the <I>iovcnt</I> buffers speci-
     fied by the members of the <I>iov</I> array: iov[0], iov[1], ..., iov[iovcnt-1].
     <B>Pwrite</B>() performs the same function, but writes to the specified position
     in the file without modifying the file pointer.

     For <B>writev</B>(), the <I>iovec</I> structure is defined as:

	   struct iovec {
		   char   *iov_base;  /* Base address. */
		   size_t iov_len;    /* Length. */
	   };

     Each <I>iovec</I> entry specifies the base address and length of an area in mem-
     ory from which data should be written.  <B>Writev</B>() will always write a com-
     plete area before proceeding to the next.

     On objects capable of seeking, the <B>write</B>() starts at a position given by
     the pointer associated with <I>d</I>, see <B><A HREF="lseek.html">lseek(2)</A></B>.  Upon return from <B>write</B>(),
     the pointer is incremented by the number of bytes which were written.

     Objects that are not capable of seeking always write from the current po-
     sition.  The value of the pointer associated with such an object is unde-
     fined.

     If the real user is not the super-user, then <B>write</B>() clears the set-user-
     id bit on a file.	This prevents penetration of system security by a user
     who ``captures'' a writable set-user-id file owned by the super-user.

     When using non-blocking I/O on objects such as sockets that are subject
     to flow control, <B>write</B>() and <B>writev</B>() may write fewer bytes than request-
     ed; the return value must be noted, and the remainder of the operation
     should be retried when possible.


</PRE>
<H2>IMPLEMENTATION NOTES</H2><PRE>
     In the non-threaded library <B>write</B>() is implemented as the <I>write</I> syscall.

     In the threaded library, the <I>write</I> syscall is assembled to
     <B>_thread_sys_write</B>() and <B>write</B>() is implemented as a function which locks
     <I>d</I> for read and write, then calls <B>_thread_sys_write</B>().  If the call to
     <B>_thread_sys_write</B>() would block, a context switch is performed. Before
     returning, <B>write</B>() unlocks <I>d</I>.

     In the non-threaded library <B>writev</B>() is implemented as the <I>writev</I>
     syscall.

     In the threaded library, the <I>writev</I> syscall is assembled to
     <B>_thread_sys_writev</B>() and <B>writev</B>() is implemented as a function which
     locks <I>d</I> for read and write, then calls <B>_thread_sys_writev</B>().  If the call
     to <B>_thread_sys_writev</B>() would block, a context switch is performed. Be-
     fore returning, <B>writev</B>() unlocks <I>d</I>.


</PRE>
<H2>RETURN VALUES</H2><PRE>
     Upon successful completion the number of bytes which were written is re-
     turned.  Otherwise a -1 is returned and the global variable <I>errno</I> is set
     to indicate the error.


</PRE>
<H2>ERRORS</H2><PRE>
     <B>Write</B>(), <B>writev</B>(), and <B>pwrite</B>() will fail and the file pointer will re-
     main unchanged if:

     [EBADF]	   <I>D</I> is not a valid descriptor open for writing.

     [EPIPE]	   An attempt is made to write to a pipe that is not open for
		   reading by any process.

     [EPIPE]	   An attempt is made to write to a socket of type SOCK_STREAM
		   that is not connected to a peer socket.

     [EFBIG]	   An attempt was made to write a file that exceeds the pro-
		   cess's file size limit or the maximum file size.

     [EFAULT]	   Part of <I>iov</I> or data to be written to the file points out-
		   side the process's allocated address space.

     [EINVAL]	   The pointer associated with <I>d</I> was negative.

     [ENOSPC]	   There is no free space remaining on the file system con-
		   taining the file.

     [EDQUOT]	   The user's quota of disk blocks on the file system contain-
		   ing the file has been exhausted.

     [EIO]	   An I/O error occurred while reading from or writing to the
		   file system.

     [EAGAIN]	   The file was marked for non-blocking I/O, and no data could
		   be written immediately.

     In addition, <B>writev</B>() may return one of the following errors:

     [EDESTADDRREQ]
		   The destination is no longer available when writing to a
		   UNIX domain datagram socket on which <B><A HREF="connect.html">connect(2)</A></B> had been
		   used to set a destination address.

     [EINVAL]	   <I>Iovcnt</I> was less than or equal to 0, or greater than
		   UIO_MAXIOV.

     [EINVAL]	   One of the <I>iov</I><B>_</B><I>len</I> values in the <I>iov</I> array was negative.

     [EINVAL]	   The sum of the <I>iov</I><B>_</B><I>len</I> values in the <I>iov</I> array overflowed a
		   32-bit integer.

     The <B>pwrite</B>() call may also return the following errors:

     [EINVAL]	   The specified file offset is invalid.

     [ESPIPE]	   The file descriptor is associated with a pipe, socket, or
		   FIFO.


</PRE>
<H2>SEE ALSO</H2><PRE>
     <B><A HREF="fcntl.html">fcntl(2)</A></B>,	<B><A HREF="lseek.html">lseek(2)</A></B>,  <B><A HREF="open.html">open(2)</A></B>,  <B><A HREF="pipe.html">pipe(2)</A></B>,  <B><A HREF="select.html">select(2)</A></B>


</PRE>
<H2>STANDARDS</H2><PRE>
     The <B>write</B>() function call is expected to conform to IEEE Std1003.1-1990
     (``POSIX''). The <B>writev</B>() and <B>pwrite</B>() functions are expected to conform
     to X/Open Portability Guide Issue 4.2 (``XPG4.2'').


</PRE>
<H2>HISTORY</H2><PRE>
     The <B>pwrite</B>() function call appeared in AT&amp;T System V.4 UNIX.  The
     <B>writev</B>() function call appeared in 4.2BSD. A <B>write</B>() function call ap-
     peared in Version 6 AT&amp;T UNIX.

4th Berkeley Distribution	 April 2, 1994				     3
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
